Personal Computer World 2007 September/PCWSEP07.iso/Software/Full/NetObjects Fusion 9 Standard/NOF9_Full_EN.exe/data1.cab/FSI/lib/innovative/container.js

JavaScript | 2005-11-16 | 11.1 KB | 506 lines

/****i* SOURCE_FILE/INFO
 *
 * NAME
 *    container.js
 *
 * USAGE
 *    Part of IS JavaScript Library.
 *
 * COPYRIGHT
 *    Copyright ⌐ 1999-2000 Innovative Systems SRL.
 *    All Rights Reserved.
 *
 *  This is an unpublished work protected by Innovative Systems SRL
 *  as a trade secret, and is not to be used or disclosed except as
 *  expressly provided in a written license agreement executed by
 *  you and Innovative Systems SRL.
 *
 *      <[e-mail]>
 *
 * NOTES
 *    JavaScript code.
 *
 *****/

/****h* IS_JavaScript_Library/container
 *
 * NAME
 *    IS JavaScript Library / container module
 *
 * DESCRIPTION
 *    Item's container functionality.
 *
 ****/

var IS = IS_getLibHandle();

if ( typeof( IS.TYPE_CONTAINER ) == "undefined" )
{
/****v* ISJS/TYPE_CONTAINER
 *
 * NAME
 *    TYPE_CONTAINER
 *
 * DESCRIPTION
 *    Const string for container type. Has the value "is_container".
 *
 ****/
IS.__proto__.TYPE_CONTAINER    = "is_container";




/****m* Container/getItemCount
 *
 * NAME
 *    getItemCount()
 *
 * USAGE
 *
 * DESCRIPTION
 *    Finds out the total number of the items managd by the container.
 *
 * RETURN VALUE
 *    Number of the items (objects) within the container
 *
 ****/
function IS_Container_getItemCount()
{
    return this.items.length;
}


/****m* Container/checkItemId
 *
 * NAME
 *    checkItemId( itemId )
 *
 * USAGE
 *    itemId -- the id of the searched item.
 *
 * DESCRIPTION
 *    Check for the existence of a menu item w/ the specified id within the collection.
 *
 * RETURN VALUE
 *    true  -û if the container contains an item with the specified id
 *    false -û in any other case
 *
 ****/
function IS_Container_checkItemId( itemId )
{
    var nItemCount = this.getItemCount();

    // check for existence of a menu item with the same id
    for ( var i = 0; i < nItemCount; i++ )
        if ( this.items[ i ].id == itemId )
            // this container already has an item with the specified id
            return true;

    // there's no item with the specified id in the container
    return false;
}


/****m* Container/getUniqueId
 *
 * NAME
 *    getUniqueId()
 *
 * USAGE
 *
 * DESCRIPTION
 *    Find out an id that is not already used within the container.
 *
 * RETURN VALUE
 *    true  -û if the container contains an item with the specified id
 *    false -û in any other case
 *
 * NOTES
 *    (*) This method is used for the auto-id feature of the container.
 *
 ****/
function IS_Container_getUniqueId()
{
    var nItemCount = this.getItemCount();

    for ( var i = nItemCount; i >= 0; i-- )
        // is there an item with the id equal to 'i'? if not, bingo!
        if ( this.checkItemId( i ) == false )
            return i;

    // you should never get here!
    // (the for loop is from length downto 0, not from length-1 downto 0, so you should
    // find a unique id in a set of length+1 choices...)
    return null;
}


/****m* Container/addItem
 *
 * NAME
 *    addItem( item )
 *
 * USAGE
 *    item -- the new item to be added
 *
 * DESCRIPTION
 *    Adds a new item to the container.
 *
 * RETURN VALUE
 *    true  -û if successful (the new item has been added)
 *    false û- if failed
 *
 * NOTES
 *    (*) If the input parameter has the id property set to null then the auto-id feature is
 *    assumed; thus an unique id is created for that item and the newly created item is added to
 *    the container.
 *
 *    (*) The request for adding a new item with an already existing id within the container
 *    will fail.
 *
 ****/
function IS_Container_addItem( item )
{
    var nItemCount = this.getItemCount();

    // auto-id? (if item's id is not specified)
    if ( null == item.id )
        item.id = this.getUniqueId();

    // check for existence of a menu item with the same id
    if ( this.checkItemId( item.id ) )
        // command failed! (this container already has an item with the same id)
        return false;

    this.items[ nItemCount ] = item;

    return true;
}


/****m* Container/removeItem
 *
 * NAME
 *    removeItem( itemId )
 *
 * USAGE
 *    itemId -- the identifier of the item to be removed
 *
 * DESCRIPTION
 *    Removes an item from the container.
 *
 * RETURN VALUE
 *    true  -û if successful (the item has been removed)
 *    false -û if failed
 *
 ****/
function IS_Container_removeItem( itemId )
{
    if ( this.checkItemId( itemId ) )
    {
        var nItemCount    = this.getItemCount();
        var newItems    = new Array( nItemCount - 1 );
        var nDelta        = 0;

        for ( var i = 0; i < nItemCount; i++ )
            if ( this.items[ i ].id == itemId )
                nDelta = 1;
            else
                newItems[ i - nDelta ] = this.items[ i ];

        this.items = null;
        this.items = newItems;

        return true;
    }

    return false;
}


/****m* Container/removeItemAt
 *
 * NAME
 *    removeItemAt( idx )
 *
 * USAGE
 *    idx -- the index of the item to be removed
 *
 * DESCRIPTION
 *    Removes an item from the container.
 *
 * RETURN VALUE
 *    true  -û if successful (the item has been removed)
 *    false -û if failed
 *
 * NOTES
 *    (*) The request to remove an item with a non-existent index within the container
 *    (idx >= getItemCount()) will fail.
 *
 ****/
function IS_Container_removeItemAt( idx )
{
    if ( ( 0 <= idx ) && ( idx < this.getItemCount() ) )
        return this.removeItem( this.items[ idx ].id );

    return false;
}


/****m* Container/removeAllItems
 *
 * NAME
 *    removeAllItems()
 *
 * USAGE
 *
 * DESCRIPTION
 *    Removes all the items within the container.
 *
 * RETURN VALUE
 *    true
 *
 * NOTES
 *    (*) The request to remove an item with a non-existent index within the container
 *    (idx >= getItemCount()) will fail.
 *
 ****/
function IS_Container_removeAllItems()
{
    this.items = null;
    this.items = new Array( 0 );

    return true;
}


/****m* Container/getItem
 *
 * NAME
 *    getItem( itemId )
 *
 * USAGE
 *    itemId -- identifier of the searched item
 *
 * DESCRIPTION
 *    Retrieve an item from container.
 *
 * RETURN VALUE
 *    [object] -û if successful (the container contains an item with the specified identifier)
 *    null     -û if failed
 *
 ****/
function IS_Container_getItem( itemId )
{
    var nItemCount = this.getItemCount();

    for ( var i = 0; i < nItemCount; i++ )
    {
        var item = this.items[ i ];

        if ( item.id == itemId )
            return item;
    }

    return null;
}


/****m* Container/setItem
 *
 * NAME
 *    setItem( itemId, newItem )
 *
 * USAGE
 *    itemId  -- identifier of the searched item
 *    newItem -- the new item
 *
 * DESCRIPTION
 *    Changes an item within the container.
 *
 * RETURN VALUE
 *    true  -û if successful (the item has been changed)
 *    false û- if failed
 *
 ****/
function IS_Container_setItem( itemId, newItem )
{
    var nItemCount = this.getItemCount();

    for ( var i = 0; i < nItemCount; i++ )
    {
        var item = this.items[ i ];

        if ( item.id == itemId )
        {
            this.items[ i ] = newItem;
            return true;
        }
    }

    return false;
}


/****m* Container/getItemAt
 *
 * NAME
 *    getItemAt( idx )
 *
 * USAGE
 *    idx -- index of the searched item
 *
 * DESCRIPTION
 *    Retrieve an item from container.
 *
 * RETURN VALUE
 *    [object] û- if successful (the container contains an item with the specified index)
 *    null     -û if failed
 *
 ****/
function IS_Container_getItemAt( idx )
{
    if ( ( 0 <= idx ) && ( idx < this.getItemCount() ) )
        return this.items[ idx ];

    return null;
}


/****m* Container/setItemAt
 *
 * NAME
 *    setItemAt( idx, newItem )
 *
 * USAGE
 *    idx     -- index of the searched item
 *    newItem -- the new item
 *
 * DESCRIPTION
 *    Changes an item within the container.
 *
 * RETURN VALUE
 *    true  -û if successful (the item has been changed)
 *    false û- if failed
 *
 * NOTES
 *    (*) The request to change an item with a non-existent index within the container
 *    (idx >= getItemCount()) will fail.
 *
 ****/
function IS_Container_setItemAt( idx, newItem )
{
    var nItemCount = this.getItemCount();

    if ( ( 0 <= idx ) && ( idx < nItemCount ) )
    {
        this.items[ idx ] = newItem;
        return true;
    }

    return false;
}


/****m* Container/pop
 *
 * NAME
 *    pop( bRemove )
 *
 * USAGE
 *    bRemove -- remove flag
 *
 * DESCRIPTION
 *    Retrieves the last item within the container. If 'bRemove' is set to true, then the item
 *    is also removed from the container; otherwise the container remains unchanged.
 *
 * RETURN VALUE
 *    [object] -û the item having the index = getItemCount() - 1, if the containers have any item
 *    null     û- if the container have no items
 *
 ****/
function IS_Container_pop( bRemove )
{
    var nItemCount = this.getItemCount();

    if ( nItemCount > 0 )
    {
        var item = this.getItemAt( nItemCount - 1 );

        if ( typeof( bRemove ) == "undefined" || bRemove == true )
            this.removeItemAt( nItemCount - 1 );

        return item;
    }

    return null;
}


/****c* ISJS/Container
 *
 * NAME
 *    ISJS::Container( id, owner )
 *
 * USAGE
 *    id    -- Object identifier.
 *           Distinguishes the container within a containers collection.
 *           Should be unique among the collection.
 *    owner -- This property is currently not used.
 *
 * DESCRIPTION
 *        An ISLib.Container object can manage a collection of objects (items.)
 *        Every object managed through a container has to have a property named æidÆ which will
 *    uniquely identify the item among the container items. A container cannot manage two objects
 *    with the same identifier.
 *        Note: a container can manage objects of different types provided that the above rule
 *    is obeyed.
 *        When adding a new item to the container if the id of the item is not specified (set to
 *    null) then a unique id is created for that item.
 *        The access to the container items may be done using:
 *            an identifier ù methods: removeItem(),   getItem(),   setItem(); or
 *            an index      ù methods: removeItemAt(), getItemAt(), setItemAt().
 *    Note: the first item has the index 0; the last item has the index getItemCount() û 1.
 *
 * NOTES
 *
 * SEE ALSO
 *
 ****/
function IS_Container( id, owner )
{
//    alert( "DBG::IS.Container"
//            + "\n id: " + id
//            + "\n owner: " + owner
//            );

    // __proto__ initialization
    this.__proto__ = IS_Container.prototype;

    // properties
    this.type    = IS.TYPE_CONTAINER;
    this.id        = id;        // must be unique among the container collection
    this.owner    = owner;    // container's owner (if any); note: for SA use, this property will be a Menu, Tree or Container object

    this.items    = new Array( 0 ); // no items at start-up

    // methods
    this.getItemCount    = IS_Container_getItemCount;
    this.checkItemId    = IS_Container_checkItemId;
    this.getUniqueId    = IS_Container_getUniqueId;
    this.addItem        = IS_Container_addItem;
    this.removeItem        = IS_Container_removeItem;
    this.removeItemAt    = IS_Container_removeItemAt;
    this.removeAllItems    = IS_Container_removeAllItems;
    this.getItem        = IS_Container_getItem;
    this.getItemAt        = IS_Container_getItemAt;
    this.setItem        = IS_Container_setItem;
    this.setItemAt        = IS_Container_setItemAt;
    this.push            = IS_Container_addItem; // same as addItem
    this.pop            = IS_Container_pop;
}

// add Container class to IS namespace
IS.__proto__.Container = IS_Container;
}